//+------------------------------------------------------------------+
//|                                                        IList.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include "ICollection.h"  // 引入基础集合接口 ICollection<T>，继承其核心操作能力

//+------------------------------------------------------------------+
//| IList<T> 泛型接口：MQL5 索引式集合标准接口                        |
//| 核心定位：继承自基础集合接口 ICollection<T>，扩展“按索引访问”能力， |
//|           定义支持通过索引单独访问、插入、删除元素的列表规范，        |
//|           为动态数组、链表等有序集合提供统一操作接口                 |
//| 泛型特性：通过模板参数 <T> 适配任意数据类型（如订单、价格、自定义结构），|
//|           确保列表操作的类型安全性，避免不同类型元素混合存储           |
//| 核心价值：作为“有序集合契约”，在基础集合的增删改查能力上，强化“索引定位”能力，|
//|           支持按位置访问元素（如获取第N个订单、修改第K个信号值），适配EA中 |
//|           需按顺序管理数据的场景（如订单执行队列、指标数据序列、信号触发列表）|
//| 与父接口关系：继承 ICollection<T> 的基础能力（Add/Count/Contains等），|
//|               新增索引相关方法（TryGetValue/Insert/IndexOf等），形成“有序集合”完整能力 |
//| 适用场景：所有需要按顺序存储并通过索引访问数据的 MQL5 程序（EA、指标、脚本），|
//|           尤其适合动态顺序调整（如插入优先级订单）、按位置修改数据（如更新第N个指标值）的场景 |
//+------------------------------------------------------------------+
template<typename T>
interface IList : public ICollection<T>
  {
   //----------------------------------------------------------------
   // 索引访问接口：通过索引读写元素（带安全检查）
   //----------------------------------------------------------------
   /**
    * @brief 通过索引安全获取元素（避免直接访问越界）
    * @param index [in] 元素索引（需满足 0 ≤ index < Count()，否则获取失败）
    * @param value [out] 输出参数，接收获取到的元素（仅当返回 true 时有意义）
    * @return bool - 操作结果：true=索引有效，成功获取元素；false=索引无效（越界或列表为空）
    * @note 相比直接通过 [] 访问，此方法通过返回值明确告知操作是否成功，避免程序异常
    */
   bool              TryGetValue(const int index, T &value);

   /**
    * @brief 通过索引安全设置元素值（避免直接修改越界）
    * @param index [in] 元素索引（需满足 0 ≤ index < Count()，否则设置失败）
    * @param value [in] 待设置的新元素值（类型与 T 一致）
    * @return bool - 操作结果：true=索引有效，成功修改元素；false=索引无效（越界或列表为空）
    * @note 适用于需要修改指定位置元素的场景（如更新第3个订单的状态）
    */
   bool              TrySetValue(const int index, T value);

   //----------------------------------------------------------------
   // 插入接口：在指定索引位置插入元素
   //----------------------------------------------------------------
   /**
    * @brief 在列表的指定索引位置插入新元素（后续元素自动后移）
    * @param index [in] 插入位置（允许 0 ≤ index ≤ Count()，index=Count() 等价于 Add()）
    * @param item [in] 待插入的元素（类型与 T 一致）
    * @return bool - 插入结果：true=插入成功（索引有效且元素符合要求）；false=插入失败（索引越界或内存不足）
    * @note 插入后列表长度自动+1，原索引及之后的元素索引均+1（如在索引2插入，原索引2的元素移至3）
    *       典型应用：在订单队列的指定位置插入高优先级订单
    */
   bool              Insert(const int index, T item);

   //----------------------------------------------------------------
   // 索引查找接口：定位元素在列表中的位置
   //----------------------------------------------------------------
   /**
    * @brief 查找元素在列表中首次出现的索引（从头部开始搜索）
    * @param item [in] 待查找的元素（类型与 T 一致）
    * @return int - 索引值：找到时返回首次出现的索引（≥0）；未找到时返回 -1
    * @note 查找逻辑依赖元素的相等性判断（基础类型用值比较，自定义类型需实现 Equals()）
    */
   int               IndexOf(T item);

   /**
    * @brief 查找元素在列表中最后一次出现的索引（从尾部开始搜索）
    * @param item [in] 待查找的元素（类型与 T 一致）
    * @return int - 索引值：找到时返回最后出现的索引（≥0）；未找到时返回 -1
    * @note 适用于存在重复元素的列表（如查找最后一个满足条件的信号）
    */
   int               LastIndexOf(T item);

   //----------------------------------------------------------------
   // 索引删除接口：移除指定位置的元素
   //----------------------------------------------------------------
   /**
    * @brief 移除列表中指定索引位置的元素（后续元素自动前移）
    * @param index [in] 待删除元素的索引（需满足 0 ≤ index < Count()，否则删除失败）
    * @return bool - 删除结果：true=删除成功（索引有效）；false=删除失败（索引越界或列表为空）
    * @note 删除后列表长度自动-1，原索引之后的元素索引均-1（如删除索引2，原索引3的元素移至2）
    *       典型应用：移除订单队列中已失效的第N个订单
    */
   bool              RemoveAt(const int index);
  };
//+------------------------------------------------------------------+